Repository navigation
Add AGENTS.md for coding agents - #120
Conversation
AGENTS.md is the vendor-neutral convention read by Cursor, Copilot, Codex and others. CLAUDE.md is a one-line import of it, so Claude Code picks it up too without the content being duplicated. Records the things that are not evident from the source: - this repo wraps Shimmer-Java-Android-API and holds no wire-format, parsing, calibration or timestamp logic of its own, so protocol fixes belong upstream - the driver arrives as version-pinned GitHub Packages artifacts, so an upstream fix only lands here once it is republished and the pin is bumped, and the pins are currently a release behind - the build root is ShimmerAndroidInstrumentDriver/, not the repo root, and a same-named module nests inside it - the two Gradle wrappers are at different versions (8.5 and 8.14.3) - a PAT with read:packages is required in ~/.gradle/gradle.properties as gpr.usr/gpr.key, or dependency resolution fails in a way that reads like a network fault - there is no CI, so nothing here is compiled on push or PR - the README links all target the retired ShimmerEngineering org Docs only. No build or source files are touched. Co-Authored-By: Claude Opus 5 <[email protected]>
AGENTS.md said this repo has no parsing logic of its own, so a protocol fix never needs porting here. That is wrong for the Bluetooth stream parser. Shimmer overrides processPacket(), processWhileStreaming(), processInstreamResponse() and clearSingleDataPacketFromBuffers() from the driver's ShimmerBluetooth, so a streaming-parse fix in the driver never reaches it, even after a republish and pin bump. The bare-ACK link-CRC fix in ShimmerResearch/Shimmer-Java-Android-API#319 is one that needs its own port. Decoding (processDataPacket() -> buildMsg()) and checkCrc() are still the driver's, and Shimmer3BLEAndroid uses the driver's parser. The section now says both. Verified on master 44b9cbc against the pinned driver, API_v0.11.7_beta. Docs only. Co-Authored-By: Claude Opus 5.5 <[email protected]>
|
Corrected the "It wraps the driver" section in ad9aa5c. It said this repo has no parsing logic of its own. That is wrong for the Bluetooth stream parser: Decoding ( Merge order: #121 adds a temporary |
ad9aa5c corrected the wrapper claim as of master. This brings it up to DEV-1148 (#121) and fills gaps in the build notes: - checkCrc() is overridden too since DEV-1148, as a stopgap until the driver pin includes DEV-1147. The section said it was the driver's. - readBattery() and readStatusLogAndStream() write straight to the socket while streaming instead of queueing, and processWhileStreaming() reads in bulk where the driver reads a byte at a time. - DEV-1147's driver fix had to be ported here by hand as DEV-1148. That is the consequence a reader needs, so it is now said outright. - The build root's gradle.properties is gitignored, and AGP refuses to build without android.useAndroidX=true. Jetifier has to stay off: it fails on a transitive jackson-core 2.18.2 (class file version 65). - DEV-1148 adds JVM unit tests (JUnit 4, returnDefaultValues). The command that runs them is documented. - "Java 11" was the source and target level. AGP 8 needs Gradle to run on JDK 17 or later. The unit-test setup and the checkCrc() override exist only on #121's branch, so this should merge after #121. Docs only. Co-Authored-By: Claude Opus 5.5 <[email protected]>
|
Pushed 2d14f82 on top of ad9aa5c. It brings the parser section up to DEV-1148 (#121) and fills some gaps in the build notes:
Merge order: AGENTS.md now describes the |
Adds
AGENTS.md, matching the twelve other Shimmer repos that now carry one.CLAUDE.mdis a one-line@AGENTS.mdimport so Claude Code picks the same file up — the content is not duplicated.Docs only; no build or source files are touched.
What it records
The repo is straightforward to read, so the file sticks to things that are not evident from the source:
It wraps the driver, it does not reimplement it.
Shimmer,Shimmer4AndroidandVerisenseDeviceAndroidextendShimmerBluetooth,Shimmer4sdkandVerisenseDevicefromShimmer-Java-Android-API. There is no wire-format, parsing, calibration or timestamp logic here, so a protocol fix belongs upstream and never needs re-writing in this repo. Grepping forcalibratortimeStampdoes hitShimmer.java, but only in changelog comments and in reads of already-calibratedObjectClusterdata.Upstream fixes do not arrive automatically. The driver comes in as version-pinned Maven artifacts from GitHub Packages, injected into every subproject by the root
build.gradle. A fix upstream reaches Android only once it is republished and the pin bumped:shimmerdrivershimmerbluetoothmanagershimmerbluetoothmanager0.11.8_beta appears never to have been published, so the pin cannot be bumped as things stand. Raised as DEV-1115 — this PR only documents the situation.Build facts that cost time otherwise:
ShimmerAndroidInstrumentDriver/(wheresettings.gradleis), not the repo root, and a same-named library module nests inside itsettings.gradle, so the inner one builds the same project with a different Gradleread:packagesis needed in~/.gradle/gradle.propertiesasgpr.usr/gpr.key, or resolution fails in a way that reads like a network fault rather than a missing credential. The property isgpr.usr; a commented-out block in the module saysgpra.usr, which is dead codeThe README links point at a retired org. Every link targets
ShimmerEngineering/ShimmerAndroidAPIand survives only on GitHub's rename redirect. Noted rather than changed, to keep this PR to one thing.Checking it
Claims about the class hierarchy and the pins are all readable in this tree; the published-version column came from the org package listing:
🤖 Generated with Claude Code